home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer)…68k, x86, SPARC, PA-RISC] / NeXTSTEP 3.3 Dev Intel.iso / NextDeveloper / Source / GNU / emacs / info / texinfo-3 < prev    next >
Text File  |  1991-01-10  |  49KB  |  1,411 lines
  1. Info file ../info/texinfo, produced by Makeinfo, -*- Text -*- from
  2. input file texinfo.texinfo.
  3.  
  4. This file documents Texinfo, a documentation system that uses a
  5. single source file to produce both on-line help and a printed manual.
  6.  
  7. This is edition 1.1 of the Texinfo documentation, and is for the
  8. Texinfo that is distributed as part of Version 18 of GNU Emacs.
  9.  
  10. Copyright (C) 1988 Free Software Foundation, Inc.
  11.  
  12. Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16. Permission is granted to copy and distribute modified versions of
  17. this manual under the conditions for verbatim copying, provided that
  18. the entire resulting derived work is distributed under the terms of a
  19. permission notice identical to this one.
  20.  
  21. Permission is granted to copy and distribute translations of this
  22. manual into another language, under the above conditions for modified
  23. versions, except that this permission notice may be stated in a
  24. translation approved by the Foundation.
  25.  
  26.  
  27. 
  28. File: texinfo,  Node: Breaks Blank-Lines Groups,  Prev: Refilling & Noindent,  Up: Formatting Paragraphs
  29.  
  30. Breaks, Blank Lines and Groups
  31. ==============================
  32.  
  33. Texinfo has several commands for making blank lines, for forcing
  34. paragraph and page breaks in the printed manual and for preventing
  35. text from running from one page to the next.
  36.  
  37. `@*'
  38.      Force a line break in the printed manual.  This command has no
  39.      effect on the Info file.
  40.  
  41. `@sp'
  42.      Generate blank lines in both the printed manual and in the Info
  43.      file.
  44.  
  45. `@br'
  46.      Force a paragraph break in the printed manual.  This command has
  47.      no effect on the Info file.
  48.  
  49. `@w'
  50.      Prevent text from being split across two lines in the printed
  51.      manual.  This command has no effect on the Info file.
  52.  
  53. `@page'
  54.      Start a new page in the printed manual.  This command has no
  55.      effect on the Info file.
  56.  
  57. `@group'
  58.      Hold text together that must appear on one printed page.  This
  59.      command has no effect on the Info file.
  60.  
  61. `@need'
  62.      Start a new printed page if required space not on this one. 
  63.      This command has no effect on the Info file.
  64.  
  65. * Menu:
  66.  
  67. * Line Breaks:: Force a line break in the printed manual.
  68. * Sp::        Generate blank lines.
  69. * Br::        Force a paragraph break in the printed manual.
  70. * W::        Prevent a paragraph break in the printed manual.
  71. * Page::    Start a new page in the printed manual.
  72. * Group::    Hold text together that must appear on one printed page.
  73. * Need::    Start a new printed page if required space not on this one.
  74.  
  75.  
  76. 
  77. File: texinfo,  Node: Line Breaks,  Next: Sp,  Prev: Breaks Blank-Lines Groups,  Up: Breaks Blank-Lines Groups
  78.  
  79. @*
  80. --
  81.  
  82. `@*' forces a line break in the printed manual.  It has no effect on
  83. the Info file output, where line breaks follow those in the source
  84. file.  If you want a line break at a certain spot in both forms of
  85. output, break the line there in the source file and put `@*' at the
  86. end of the line.
  87.  
  88.  
  89. 
  90. File: texinfo,  Node: Sp,  Next: Br,  Prev: Line Breaks,  Up: Breaks Blank-Lines Groups
  91.  
  92. @sp
  93. ---
  94.  
  95. A line containing `@sp N' generates N blank lines of space in either
  96. the printed manual or the Info file.  For example,
  97.  
  98.      @sp 2
  99.  
  100. generates two blank lines.
  101.  
  102.  
  103. 
  104. File: texinfo,  Node: Br,  Next: W,  Prev: Sp,  Up: Breaks Blank-Lines Groups
  105.  
  106. @br
  107. ---
  108.  
  109. In a printed manual, a line containing `@br' forces a paragraph
  110. break; in the Info file output, it does nothing (not even a blank
  111. line results from it).
  112.  
  113.  
  114. 
  115. File: texinfo,  Node: W,  Next: Page,  Prev: Br,  Up: Breaks Blank-Lines Groups
  116.  
  117. @w
  118. --
  119.  
  120. In a printed manual, `@w{TEXT}' outputs TEXT and prohibits line
  121. breaks within TEXT.  `@w' has no effect on the Info file output; it
  122. is the same as would result from just TEXT.
  123.  
  124.  
  125. 
  126. File: texinfo,  Node: Page,  Next: Group,  Prev: W,  Up: Breaks Blank-Lines Groups
  127.  
  128. @page
  129. -----
  130.  
  131. A line containing `@page' starts a new page in a printed manual.  The
  132. line has no effect on Info files since they are not paginated.
  133.  
  134.  
  135. 
  136. File: texinfo,  Node: Group,  Next: Need,  Prev: Page,  Up: Breaks Blank-Lines Groups
  137.  
  138. @group
  139. ------
  140.  
  141. A line containing `@group' begins an unsplittable vertical group,
  142. which must appear entirely on one page.  The group is terminated by a
  143. line containing `@end group'.  These two lines produce no output of
  144. their own, and in the Info file output they have no effect at all.
  145.  
  146. If you forget to end a group, you may get strange and unfathomable
  147. error messages when you run TeX.  This is because TeX keeps trying to
  148. put the rest of the Texinfo file into the group and error messages do
  149. not start to get generated until TeX has gone a long way.  It's a
  150. good rule of thumb to look for a missing `@end group' if you get
  151. incomprehensible error messages in TeX.
  152.  
  153.  
  154. 
  155. File: texinfo,  Node: Need,  Prev: Group,  Up: Breaks Blank-Lines Groups
  156.  
  157. @need
  158. -----
  159.  
  160. A line containing `@need N' starts a new page in a printed manual if
  161. fewer than N mils (thousandths of an inch) remain on the current
  162. page.  The line has no effect on Info files since they are not
  163. paginated.
  164.  
  165.  
  166. 
  167. File: texinfo,  Node: Marking Text,  Next: Conditionals,  Prev: Formatting Paragraphs,  Up: Top
  168.  
  169. Marking Text Within a Paragraph
  170. *******************************
  171.  
  172. In Texinfo, text within a paragraph can be marked in a variety of ways.
  173. The most important way is to specify whether a word or phrase is a
  174. definition, a metasyntactic variable, a literal example of a program
  175. or what not.
  176.  
  177. In addition, there are special commands for inserting single
  178. characters  that have special meaning in Texinfo, such as braces, and
  179. for inserting symbols with special handling, such as dots and
  180. bullets.  Finally, there are ways to emphasize words.
  181.  
  182. * Menu:
  183.  
  184. * Specifying::            Specifying commands, files and so on.
  185. * Braces Atsigns Periods::    Inserting braces, `@' and periods.
  186. * Dots Bullets Tex::        Inserting dots, bullets and the TeX logo
  187. * Emphasis::            Emphasizing text.
  188.  
  189.  
  190. 
  191. File: texinfo,  Node: Specifying,  Next: Braces Atsigns Periods,  Up: Marking Text
  192.  
  193. Specifying Definitions, Files, Commands etc.
  194. ============================================
  195.  
  196. Texinfo has a variety of commands for specifying just what kind of
  197. object a piece of text refers to.  Metasyntactic variables, for
  198. example, are marked by one @-command and code by another.  Texinfo
  199. uses this information to determine how to highlight the text.  Since
  200. the pieces of text are labelled by commands that tell what kind of
  201. object they are, it is easy to change the way Texinfo formats and
  202. typesets such text.  For example, code is usually illustrated in a
  203. typewriter font, but it would be easy to change the way Texinfo
  204. highlights code to use another font.  This change would not effect
  205. how metasyntatic variables are highlighted.  If straight typesetting
  206. commands were used in the body of the file, you would have to check
  207. every single occurrence to make sure that you were changing code and
  208. not something else that should not be changed.
  209.  
  210. In addition, the commands can be used to generate useful information
  211. from the file, such as lists of functions or file names.  It is
  212. possible, for example, to write code in Emacs Lisp (or a keyboard
  213. macro) to insert an index entry after every paragraph that contains
  214. the text labelled by a specified command.  You could do this to
  215. construct an index of functions if you had not already made the
  216. entries.
  217.  
  218. The commands serve a variety of purposes:
  219.  
  220. `@code'
  221.      Indicates text that is a literal example of a piece of a program.
  222.  
  223. `@samp'
  224.      Indicates text that is a literal example of a sequence of
  225.      characters.
  226.  
  227. `@file'
  228.      Indicates the name of a file.
  229.  
  230. `@kbd'
  231.      Indicates the names of keys on the keyboard or characters you
  232.      type.
  233.  
  234. `@key'
  235.      Used for the conventional name for a key on a keyboard.
  236.  
  237. `@ctrl'
  238.      Indicates an ASCII control character.
  239.  
  240. `@var'
  241.      Indicates a metasyntactic variable.
  242.  
  243. `@dfn'
  244.      Indicates the introductory or defining use of a term.
  245.  
  246. `@cite'
  247.      Indicates the name of a book.
  248.  
  249. * Menu:
  250.  
  251. * Code::    A literal example of a piece of a program.
  252. * Samp::    A literal example of a sequence of characters.
  253. * File::    The name of a file.
  254. * Kbd::        The names of keys or else characters you type.
  255. * Key::        The conventional name for a key on a keyboard.
  256. * Ctrl::    Indicates the ASCII control character.
  257. * Var::        A variable.
  258. * Dfn::        The introductory or defining use of a term.
  259. * Cite::    The name of a book.
  260.  
  261.  
  262. 
  263. File: texinfo,  Node: Code,  Next: Samp,  Up: Specifying
  264.  
  265. @code
  266. -----
  267.  
  268. `@code' is used to indicate text that is a piece of a program which
  269. consists of entire syntactic tokens.  The text follows, enclosed in
  270. braces.
  271.  
  272. For example, `@code' is used for an expression in a program, the name
  273. of a variable or function used in a program, or a keyword.  `@code'
  274. is not used for a piece of a token, such as when speaking about the
  275. characters used in a token; for example, when you are explaining what
  276. letters or printable symbols can be used in the names of functions. 
  277. It is also not used for input to programs unless the input is written
  278. in a language that is like a programming language.  For example, it
  279. is not used for the single character commands of GNU Emacs although
  280. it is used for the names of Emacs Lisp functions that the keyboard
  281. commands invoke.
  282.  
  283. You should also `@code' for command names in command languages that
  284. resemble programming languages, such as Texinfo or the shell.  Note,
  285. however, that `@code' is not used for options such as `-c' when such
  286. options stand alone.  There is some argument as to whether an entire
  287. shell command incorporating an option should be written using `@code'
  288. or `@samp'.
  289.  
  290. It is an error to alter the case of a word inside an `@code' command.
  291. This is a particularly insidious error if the language being
  292. documented is case sensitive.  If the command is `printf', then
  293. `Printf' is a misspelling.  If you do not like having such a command
  294. with lower case at the beginning of a sentence, you may wish to
  295. rearrange the sentence.
  296.  
  297. In the printed manual, `@code' puts the argument in bold face.  In
  298. the Info file, it uses `...' quotation.  For example:
  299.  
  300.      To compare two files, showing text inserted or removed, use @code{diff}.
  301.  
  302.  produces
  303.  
  304.      To compare two files, showing text inserted or removed, use
  305.      `diff'.
  306.  
  307.  
  308. 
  309. File: texinfo,  Node: Samp,  Next: File,  Prev: Code,  Up: Specifying
  310.  
  311. @samp
  312. -----
  313.  
  314. `@samp' is used to indicate text that is a literal example of a
  315. sequence of characters in a file, string, pattern, etc.  The text
  316. follows, enclosed in braces.  The argument appears within `...'
  317. quotation in both the Info file and the printed manual; in addition,
  318. it is printed in a fixed-width font.
  319.  
  320.      To match @samp{foo} at the end of the line, use the regexp @samp{foo$}.
  321.  
  322.  produces
  323.  
  324.      To match `foo' at the end of the line, use the regexp `foo$'.
  325.  
  326. Any time you are referring to single characters, you should use
  327. `@samp' unless `@kbd' is more appropriate.  Basically, `@samp' is a
  328. catchall for whatever is not covered by `@code', `@file', `@kbd'.
  329.  
  330. Punctuation marks that are part of the English text that surrounds
  331. the strings you are specifying are *never* included within the
  332. braces.  In the following sentence, for example, the commas and
  333. period are outside of the braces:
  334.  
  335.      A symbol name ends in @samp{a}, @samp{b}, or @samp{c}.
  336.  
  337.  
  338. 
  339. File: texinfo,  Node: File,  Next: Kbd,  Prev: Samp,  Up: Specifying
  340.  
  341. @file
  342. -----
  343.  
  344. `@file' is used to indicate text that is the name of a file or
  345. directory.  Currently, it is equivalent to `@samp' in its effects on
  346. the output.  For example,
  347.  
  348.      The @file{.el} files are in 
  349.      the @file{/gnu/emacs/lisp} directory.
  350.  
  351.  produces
  352.  
  353.      The `.el' files are in  the `/gnu/emacs/lisp' directory.
  354.  
  355.  
  356. 
  357. File: texinfo,  Node: Kbd,  Next: Key,  Prev: File,  Up: Specifying
  358.  
  359. @kbd
  360. ----
  361.  
  362. `@kbd' is used much like `@code'.  The difference is that `@kbd' is
  363. for names of keys on the keyboard, or of characters you can type. 
  364. For example, to refer to the command `M-a', you would use
  365.  
  366.      @kbd{M-a}
  367.  
  368. and to refer to `M-x shell', you would use
  369.  
  370.      @kbd{M-x shell}
  371.  
  372. The `@kbd' command has the same effect as `@code' in Info, but may
  373. produce a different font in a printed manual.
  374.  
  375. You can embed another @-command inside the braces of a `@kbd'
  376. command.  This is the way to describe a command that would be
  377. described more verbosely as "press an `r' and then press the RET key":
  378.  
  379.      @kbd{r @key{RET}}
  380.  
  381. This produces: `r RET'
  382.  
  383. You also use the `@kbd' command if you are spelling out the letters
  384. you type; for example:
  385.  
  386.      To give the @code{logout} command, 
  387.      type the characters @kbd{l o g o u t @key{RET}}.
  388.  
  389.  This produces
  390.  
  391.      To give the `logout' command,  type the characters `l o g o u t
  392.      RET'.
  393.  
  394.  
  395. 
  396. File: texinfo,  Node: Key,  Next: Ctrl,  Prev: Kbd,  Up: Specifying
  397.  
  398. @key
  399. ----
  400.  
  401. `@key' is used for the conventional name for a key on a keyboard, as in
  402.  
  403.      @key{RET}
  404.  
  405. Often, `@key' is used within the argument of a `@kbd' command,
  406. whenever the sequence of characters to be typed includes one or more
  407. keys that are described by name.
  408.  
  409. For example, to produce `C-x ESC' you would use
  410.  
  411.      @kbd{C-x @key{ESC}}
  412.  
  413. The recommended names to use for keys are in upper case and are
  414.  
  415. SPC
  416.      Space.
  417.  
  418. RET
  419.      Return.
  420.  
  421. LFD
  422.      Linefeed.
  423.  
  424. TAB
  425.      Tab.
  426.  
  427. BS
  428.      Backspace.
  429.  
  430. ESC
  431.      Escape.
  432.  
  433. DEL
  434.      Delete.
  435.  
  436. SFT
  437.      Shift.
  438.  
  439. CTL
  440.      Control.
  441.  
  442. META
  443.      Meta.
  444.  
  445. There are subtleties to handling words like `meta' or `ctrl' which
  446. are names of shift keys.  When mentioning a character in which the
  447. shift key is used, such as `Meta-a', use the `@kbd' command alone
  448. without the `@key' command, but when you are referring to shift key
  449. in isolation, use the `@key' command.  For example, you would use
  450. `@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce META.
  451.  
  452.  
  453. 
  454. File: texinfo,  Node: Ctrl,  Next: Var,  Prev: Key,  Up: Specifying
  455.  
  456. @ctrl
  457. -----
  458.  
  459. `@ctrl' is used to describe an ASCII control character.  The pattern
  460. of usage is `@ctrl{CH}', where CH is an ASCII character whose
  461. control-equivalent is wanted.  Thus, you put in an `f' when you want
  462. to indicate a `control-f'
  463.  
  464. Thus, to specify `control-f', you would enter
  465.  
  466.      @ctrl{f}
  467.  
  468. which produces
  469.  
  470.      f
  471.  
  472. In the Info file, this generates the specified control character,
  473. output literally into the file.  This is done so a user can copy the
  474. specified control character (along with whatever else he or she
  475. wants) into another Emacs buffer and use it.  Since the
  476. `control-h',`control-i', and `control-j' characters are formatting
  477. characters, they should not be indicated this way.
  478.  
  479. In a printed manual, this generates text to describe or identify that
  480. control character: an uparrow followed by the character CH.
  481.  
  482.  
  483. 
  484. File: texinfo,  Node: Var,  Next: Dfn,  Prev: Ctrl,  Up: Specifying
  485.  
  486. @var
  487. ----
  488.  
  489. `@var' is used to indicate metasyntactic variables.  A metasyntactic
  490. variable is something that stands for another piece of text.  You
  491. would use a metasyntactic variable in the documentation of a function
  492. to describe the arguments that are passed to that function.
  493.  
  494. `@var' is not used for names of particular variables in programming
  495. languages.  For example, the Texinfo variable `texinfo-tex-command'
  496. is not a metasyntactic variable.
  497.  
  498. Its effect in the Info file is to upcase the argument; in the printed
  499. manual, to italicize it.  Example:
  500.  
  501.      To delete file @var{filename}, type @code{rm @var{filename}}.
  502.  
  503.  produces
  504.  
  505.      To delete file FILENAME, type `rm FILENAME'.
  506.  
  507. In some documentation styles, metasyntactic variables are shown with
  508. angle brackets, for example:
  509.  
  510.      ..., type rm <filename>
  511.  
  512.  
  513. 
  514. File: texinfo,  Node: Dfn,  Next: Cite,  Prev: Var,  Up: Specifying
  515.  
  516. @dfn
  517. ----
  518.  
  519. `@dfn' is used to identify the introductory or defining use of a
  520. technical term.  The command should be used only in a passage whose
  521. purpose is to introduce a term which will be used again or which the
  522. reader ought to know.  Mere passing mention of a term for the first
  523. time doesn't deserve `@dfn'.  It generates italics in the printed
  524. manual, and double quotation marks in the Info file.  Example:
  525.  
  526.      Getting rid of a file is called @dfn{deleting} it.
  527.  
  528.  produces
  529.  
  530.      Getting rid of a file is called "deleting" it.
  531.  
  532.  
  533. 
  534. File: texinfo,  Node: Cite,  Prev: Dfn,  Up: Specifying
  535.  
  536. @cite
  537. -----
  538.  
  539. `@cite' is used for the name of a book.  It produces italics in the
  540. printed manual, and quotation marks in the Info file.
  541.  
  542.  
  543. 
  544. File: texinfo,  Node: Braces Atsigns Periods,  Next: Dots Bullets Tex,  Prev: Specifying,  Up: Marking Text
  545.  
  546. Inserting Braces, `@' and Periods
  547. =================================
  548.  
  549. `@' and curly braces are special characters in Texinfo.  This means
  550. that you have to put an `@' in front of these characters in order to
  551. insert them into text.
  552.  
  553. Periods are also special.  Depending on whether the period is inside
  554. of or at the end of a sentence, less or more space is inserted after
  555. a period in a typeset manual.  Since it is not always possible for
  556. Texinfo to determine when a period ends a sentence and when it is
  557. used in an abbreviation, special commands are needed.  (Usually,
  558. Texinfo figures out how to handle periods, so you don't have to use
  559. the special commands; you just enter a period as you would if you
  560. were using a typewriter, which means you put two spaces after the
  561. period that ends a sentence and after a colon.)
  562.  
  563. * Menu:
  564.  
  565. * Inserting an Atsign::        inserting an atsign.
  566. * Insert Left Brace::        Inserting a left brace.
  567. * Insert Colon::        Preventing unintended additional whitespace.
  568. * Insert Period::         Inserting a period that does end a sentence.
  569.  
  570.  
  571. 
  572. File: texinfo,  Node: Inserting An Atsign,  Next: Insert Left Brace,  Up: Braces Atsigns Periods
  573.  
  574. @@
  575. --
  576.  
  577. `@@' stands for a single @ in either printed or Info output.
  578.  
  579.  
  580. 
  581. File: texinfo,  Node: Insert Left Brace,  Next: Insert Colon,  Prev: Inserting an Atsign,  Up: Braces Atsigns Periods
  582.  
  583. @{
  584. --
  585.  
  586. `@{' stands for a single { in either printed or Info output.
  587.  
  588. @}
  589. --
  590.  
  591. `@}' stands for a single } in either printed or Info output.
  592.  
  593.  
  594. 
  595. File: texinfo,  Node: Insert Colon,  Next: Insert Period,  Prev: Insert Left Brace,  Up: Braces Atsigns Periods
  596.  
  597. @:
  598. --
  599.  
  600. `@:' is used after a character such as period or colon which normally
  601. causes TeX to increase the width of the following whitespace, to
  602. suppress that effect.  For example, it can be used after periods that
  603. end abbreviations and do not end sentences.  `@:' has no effect on
  604. the Info file output.
  605.  
  606.      It displays @code{Foo:}@: at that time.
  607.  
  608.  produces
  609.  
  610.      It displays `Foo:' at that time.
  611.  
  612. The meanings of `@:' and `@.' in Texinfo are designed to work well
  613. with the Emacs sentence motion commands.  This means they are
  614. different from their meanings in some other formatting systems that
  615. use @-commands.
  616.  
  617.  
  618. 
  619. File: texinfo,  Node: Insert Period,  Prev: Insert Colon,  Up: Braces Atsigns Periods
  620.  
  621. @.
  622. --
  623.  
  624. `@.' stands for a period that really does end a sentence, useful when
  625. TeX would otherwise assume by its heuristics that that is not so. 
  626. This happens when there is a single-capital-letter word at the end of
  627. a sentence: TeX normally guesses that it is an abbreviation.
  628.  
  629. In the Info file output, `@.' is equivalent to a simple `.'.  The
  630. Texinfo program preserves the amount of space that you use, so put
  631. two spaces after a period if you intend it to be the end of a
  632. sentence (as well as using `@.', if necessary, for the printed
  633. manual's sake).
  634.  
  635.      Give it to X. Give it to X@.  Give it to X@.
  636.  
  637.  produces
  638.  
  639.      Give it to X. Give it to X.  Give it to X.
  640.  
  641.  
  642. 
  643. File: texinfo,  Node: Dots Bullets Tex,  Next: Emphasis,  Prev: Braces Atsigns Periods,  Up: Marking Text
  644.  
  645. Inserting Dots, Bullets and TeX
  646. ===============================
  647.  
  648. An ellipsis, a line of dots, is typeset differently than a string of
  649. periods; more whitespace is put between the dots in the ellipsis than
  650. is put between the periods.  Because of this, a special command is
  651. used in Texinfo for inserting dots.  Also, the trademark, TeX, is
  652. typeset in a special fashion and it needs an @-command, as does the
  653. command for inserting the copyright symbol.  The `@bullet' command is
  654. special, too.  Each of these commands is followed by a pair of
  655. braces, `{}', without any whitespace between the name of the command
  656. and the braces.
  657.  
  658. * Menu:
  659.  
  660. * Dots::        Inserting dots.
  661. * Bullet::        Inserting bullets.
  662. * Tex::            Inserting the TeX trademark.
  663.  
  664.  
  665. 
  666. File: texinfo,  Node: Dots,  Next: Bullet,  Up: Dots Bullets Tex
  667.  
  668. @dots{}
  669. -------
  670.  
  671. `@dots{}' generates an ellipsis which is three dots in a row,
  672. appropriately spaced, like this: `...'.  Do not simply write three
  673. periods in the input file; that would work for the Info file output,
  674. but would produce the wrong amount of space between the periods in
  675. the printed manual.
  676.  
  677.  
  678. 
  679. File: texinfo,  Node: Bullet,  Next: Tex,  Prev: Dots,  Up: Dots Bullets Tex
  680.  
  681. @bullet{}
  682. ---------
  683.  
  684. `@bullet{}' generates a large round dot, or the closest possible
  685. thing to one.
  686.  
  687. Here is a bullet: *
  688.  
  689.  
  690. 
  691. File: texinfo,  Node: Tex,  Prev: Bullet,  Up: Dots Bullets Tex
  692.  
  693. @TeX{}
  694. ------
  695.  
  696. `@TeX{}' generates `TeX'.  In a printed manual, this is a special
  697. logo that is different from three ordinary letters.
  698.  
  699.  
  700. 
  701. File: texinfo,  Node: Emphasis,  Prev: Dots Bullets Tex,  Up: Marking Text
  702.  
  703. Emphasizing Text
  704. ================
  705.  
  706. Usually, Texinfo changes the font automatically to mark words in the
  707. text according to what category the words belong to.  The `@code'
  708. command, for example, does this.  Most often, this is the best way to
  709. mark specified words.  However, sometimes you will want to emphasize
  710. text directly.  Texinfo has two ways to do this: commands that tell
  711. Texinfo to emphasize the text but leave the method to the program,
  712. and commands that specify the font to use.  The first method is
  713. generally the best and it makes it possible to change the style of a
  714. document without have to re-edit it line by line.
  715.  
  716. * Menu:
  717.  
  718. * Emph and Strong::    Emphasizing text.
  719. * Fonts::        Selecting italic, bold or typewriter fonts.
  720.  
  721.  
  722. 
  723. File: texinfo,  Node: Emph and Strong,  Next: Fonts,  Up: Emphasis
  724.  
  725. @emph and @strong
  726. -----------------
  727.  
  728. `@emph' and `@strong' are two forms of emphasis.  `@strong' is
  729. stronger.
  730.  
  731. In printed output, `@emph' produces *italics* and `@strong' produces
  732. *bold*.
  733.  
  734. In the Info file, both of these commands put asterisks around the
  735. argument.
  736.  
  737.  
  738. 
  739. File: texinfo,  Node: Fonts,  Prev: Emph and Strong,  Up: Emphasis
  740.  
  741. @i,  @b and @t
  742. --------------
  743.  
  744. These three commands specify font changes in the printed manual and
  745. have no effect in the Info file.  `@i' requests italic font (in some
  746. versions of TeX, a slanted font is used), `@b' requests bold face,
  747. and `@t' requests the fixed-width font used by `@kbd'.  All three
  748. commands apply to an argument that follows, surrounded by braces.
  749.  
  750. If possible, you should avoid using these three commands.  If you
  751. find a need to use one, it probably indicates a lack in the Texinfo
  752. language.
  753.  
  754.  
  755. 
  756. File: texinfo,  Node: Conditionals,  Next: Printing Hardcopy,  Prev: Marking Text,  Up: Top
  757.  
  758. Conditionals
  759. ************
  760.  
  761. You may not always be able to use the same text for both the printed
  762. manual and the on-line Info file.  In this case, you can use the
  763. conditional commands to specify which text is for the printed manual
  764. and which is for the Info file.
  765.  
  766. `@ifinfo' begins text that should be ignored by TeX when it typesets
  767. the printed manual.  The text appears only in the Info file.  The
  768. `@ifinfo' command should appear on a line by itself.  End the
  769. info-only text with a line containing `@end ifinfo' by itself.  At
  770. the beginning of a Texinfo file, the Info permissions are contained
  771. within a region marked by `@ifinfo' and `@end ifinfo'.
  772.  
  773. Likewise, `@iftex' and `@end iftex' lines delimit text that will not
  774. appear in the Info file but will appear in the printed manual.
  775.  
  776. For example,
  777.  
  778.      @iftex
  779.      This text will appear only in the printed manual.
  780.      @end iftex
  781.      
  782.      
  783.      @ifinfo
  784.      However, this text will appear only in the info manual.
  785.      @end ifinfo
  786.  
  787. The preceding example produces the following.  Note how you only see
  788. one of the two lines, depending on whether you are reading the
  789. on-line Info version or the printed version of this manual.
  790.  
  791. However, this text will appear only in the info manual.
  792.  
  793. The `@titlepage' command is a special variant of `@iftex' that is
  794. used for making the title and copyright pages of the printed manual.
  795.  
  796. * Menu:
  797.  
  798. * Using Tex Commands::        Using commands from regular TeX.
  799.  
  800.  
  801. 
  802. File: texinfo,  Node: Using Tex Commands,  Prev: Conditionals,  Up: Conditionals
  803.  
  804. Using TeX Commands
  805. ==================
  806.  
  807. Inside a region delineated by `@iftex' and `@end iftex', you can
  808. embed ordinary TeX commands.  Info will ignore these commands since
  809. they are only in that part of the file that is seen by TeX.  The TeX
  810. commands are the same as any TeX commands except that an `@' replaces
  811. the `\' used by TeX.  For example, in the `@titlepage' section of a
  812. Texinfo file, the TeX command `@vskip' is used to format the
  813. copyright page.
  814.  
  815. You can enter TeX completely, and use `\' in the TeX commands by
  816. delineating a region with the `@tex' and `@end tex' commands.  (These
  817. commands automatically put the region inside of `@iftex' and `@end
  818. iftex' commands.)  For example,
  819.  
  820.      @tex
  821.      Here you would put text with TeX commands;
  822.      such as $\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$
  823.      that will appear only  in the printed manual.
  824.      @end tex
  825.  
  826. In the Info file, nothing between `@tex' and `@end tex' will appear.
  827.  
  828.  
  829. 
  830. File: texinfo,  Node: Printing Hardcopy,  Next: Creating an Info File,  Prev: Conditionals,  Up: Top
  831.  
  832. Printing Hardcopy
  833. *****************
  834.  
  835. There are three shell commands for printing a hardcopy of a Texinfo
  836. file.  One is for formatting the file, the second is for sorting the
  837. index and the third is for printing the formatted document.  When you
  838. use the shell commands, you can either work directly in the operating
  839. system shell or work within a shell inside of GNU Emacs.
  840.  
  841. The typesetting program TeX is used for formatting a Texinfo file. 
  842. TeX is a very powerful typesetting program and, if used right, does
  843. an exceptionally good job.  The @-commands in a Texinfo file are
  844. translated by a file called `texinfo.tex' into commands that TeX
  845. understands.  (That is why the beginning of every Texinfo file starts
  846. with the line that says `\input texinfo'; this command tells TeX to
  847. use the `texinfo.tex' file in processing the Texinfo file. 
  848. Customarily, `texinfo.tex' is in a directory called
  849. `/usr/lib/tex/macros'.) `texinfo-format-buffer' reads the very same
  850. @-commands in the Texinfo file and processes them differently from
  851. TeX to make an Info file.
  852.  
  853. Usually, the TeX formatting command is the shell command `tex'
  854. followed by the name of the Texinfo file.  The TeX command produces a
  855. formatted DVI file as well as several auxiliary files containing
  856. indices, cross references, etc.  The DVI file (for "DeVice
  857. Independent" file) can be printed on a wide variety of printers.
  858.  
  859. The TeX formatting command itself does not sort the indices.  This is
  860. a misfeature of TeX.  Hence, to generate a printed index, you first
  861. need a sorted index to work from.
  862.  
  863. TeX outputs raw, unsorted index files under names that obey a
  864. standard convention.  These names are the name of your main input
  865. file to TeX, with everything after the first period thrown away, and
  866. the two letter names of indices added at the end.  For example, the
  867. raw index output files for the input file `foo.texinfo' would be
  868. `foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'.  Those
  869. are exactly the arguments to give to `texindex'.  Or else, you can
  870. use `??' as "wild-cards" and give the command in this form:
  871.  
  872.      texindex foo.??
  873.  
  874.  For each file specified, `texindex' generates a sorted index file
  875. whose name is made by appending `s' to the input file name.  The
  876. `@printindex' command knows to look for a file of that name. 
  877. `texindex' does not alter the raw index output file. After you have
  878. sorted the indices, you need to rerun the TeX command on the Texinfo
  879. file.  This regenerates a formatted DVI file with the index entries
  880. in the correct order.
  881.  
  882. To summarize, this is a three step process:
  883.  
  884.   1. Run the TeX command on the Texinfo file.  This generates the
  885.      formatted DVI file as well as the raw index files with two
  886.      letter extensions.
  887.  
  888.   2. Run the shell command `texindex' on the raw index files to sort
  889.      them.  The arguments to `texindex' are the names of the raw
  890.      index files.  `texindex' creates sorted index files whose names
  891.      are the names of the raw index files with an `s' appended.  To
  892.      cause `texindex' to sort all the raw index files, append `??' to
  893.      the Texinfo file name in place of the `.texinfo' extension.
  894.  
  895.   3. Rerun the TeX command on the Texinfo file.  This regenerates a
  896.      formatted DVI file with the index entries in the correct order. 
  897.      This second run also makes all the cross references correct as
  898.      well.  (The tables of contents are always correct.)
  899.  
  900. You need not run `texindex' after each TeX run.  If you don't, the
  901. next TeX run will use whatever sorted index files happen to exist
  902. from the previous use of `texindex'.  This is usually ok while you
  903. are debugging.
  904.  
  905. Finally, the document can be printed out with the DVI print command
  906. (a shell command).  Depending on the system used, the DVI print
  907. command will be a command such as `lpr -d'.  The DVI print command
  908. may require a file name without any extension or with a `.dvi'
  909. extension.
  910.  
  911. The following commands, for example, sort the indices, format and
  912. print the ``Bison Manual'' (where `%' is the shell prompt):
  913.  
  914.      % tex bison.texinfo
  915.      % texindex bison.??
  916.      % tex bison.texinfo
  917.      % lpr -d bison.dvi
  918.  
  919. (Remember that the words for the shell commands may be different at
  920. your site; but these are commonly used versions.)
  921.  
  922. It is often most convenient to give formatting and printing commands
  923. from a shell within GNU Emacs.  This way, you can easily keep track
  924. of errors.  To create a shell within Emacs, type `M-x shell'.  In
  925. this shell, you can format and print the document.  You can switch to
  926. and from this shell while it is running and do other things.  If you
  927. are formatting a very long document on a slow machine, this can be
  928. very convenient; on a VAX 750, for example, formatting often takes 8
  929. seconds or more per page depending on how loaded the computer is. 
  930. Faster machines take correspondingly less time.
  931.  
  932. * Menu:
  933.  
  934. * Requirements::    Formatting requirements.
  935. * Compile-Command::    Formatting with the compile command.
  936.  
  937.  
  938. 
  939. File: texinfo,  Node: Requirements,  Next: Compile-Command,  Up: Printing Hardcopy
  940.  
  941. Formatting Requirements
  942. =======================
  943.  
  944. Every Texinfo file that is to be input to TeX must begin with a line
  945. that looks like
  946.  
  947.      \input texinfo   @c -*-texinfo-*-
  948.  
  949. This serves two functions.
  950.  
  951.   1. When the file is processed by TeX, it loads the macros needed
  952.      for processing a Texinfo file.
  953.  
  954.   2. When the file is edited in Emacs, it causes Texinfo mode to be
  955.      used.
  956.  
  957. Every Texinfo file must end with a line saying
  958.  
  959.      @bye
  960.  
  961. which terminates TeX processing and forces out unfinished pages.
  962.  
  963. You also have to include two lines that specify the Info file name
  964. and the title of the printed manual:
  965.  
  966.      @setfilename NAME-OF-TEXINFO-FILE
  967.      @settitle NAME OF MANUAL
  968.  
  969. You might also want to include a line saying
  970.  
  971.      @setchapternewpage odd
  972.  
  973. to cause each chapter to start on a fresh odd-numbered page.
  974.  
  975. By default, TeX typesets pages for printing in an 8.5 by 11 inch
  976. format.  However, you can direct TeX to typeset a document in a 7 by
  977. 9.25 inch format that is suitable for bound books by inserting the
  978. following command on a line by itself at the beginning of the Texinfo
  979. file, before the `@setchapternewpage' command:
  980.  
  981.      @smallbook
  982.  
  983. The Free Software Foundation distributes printed copies of the ``GNU
  984. Emacs Manual'' in this size.
  985.  
  986. Finally, TeX sometimes is unable to typeset a line without extending
  987. it into the right margin.  This can occur when TeX comes upon what it
  988. interprets as a long word that it cannot hyphenate, like a net
  989. address, or a very long title.  When this happens, TeX prints an
  990. error message like this:
  991.  
  992.      Overfull \hbox (20.76302pt too wide)
  993.  
  994. and gives the line number along with the text of the offending line
  995. marked at all the places that TeX knows to hyphenate words.  (In TeX
  996. lines are in `horizontal boxes', hence the term, `hbox'.)
  997.  
  998. If the Texinfo file has an overfull hbox, you can rewrite the
  999. sentence so the overfull hbox does not occur or you can decide to
  1000. leave it.  A small excursion into the right margin often does not
  1001. matter and may not even be noticable.  However, unless told
  1002. otherwise, TeX will print a large, ugly, black rectangle beside every
  1003. line that is overfull.  This is so you will notice the location of
  1004. the problem if you are correcting a draft.  To prevent such
  1005. monstrosities from marring your final printout, put the following in
  1006. the beginning of the Texinfo file on lines of their own, before the
  1007. `@setchapternewpage' command:
  1008.  
  1009.      @iftex
  1010.      @finalout
  1011.      @end iftex
  1012.  
  1013. *Note Titlepage::, for information about creating a title page. 
  1014. *Note Contents::, for information about creating a table of contents.
  1015.  
  1016.  
  1017. 
  1018. File: texinfo,  Node: Compile-Command,  Prev: Requirements,  Up: Printing Hardcopy
  1019.  
  1020. Using Local Variables and the Compile Command
  1021. =============================================
  1022.  
  1023. Another way to give the TeX formatting command to Texinfo is to put
  1024. that command in a "local variables list" at the end of the Texinfo
  1025. file.  You can then specify the TeX formatting command as a
  1026. `compile-command' and have Emacs run the TeX formatting command by
  1027. giving the command `M-x compile'.  This creates a special shell
  1028. called the `*compilation buffer*'.  For example, at the end of the
  1029. `gdb.texinfo' file, after the `@bye', you would put the following:
  1030.  
  1031.      @c Local Variables:
  1032.      @c compile-command: "tex gdb.texinfo"
  1033.      @c End:
  1034.  
  1035. This technique is most often used by programmers who compile programs
  1036. this way.
  1037.  
  1038.  
  1039. 
  1040. File: texinfo,  Node: Creating an Info File,  Next: Catching Mistakes,  Prev: Printing Hardcopy,  Up: Top
  1041.  
  1042. Creating an On-line Info file
  1043. *****************************
  1044.  
  1045. In GNU Emacs, using Texinfo mode, you can see what part or all of a
  1046. Texinfo file will look like in Info by using the keyboard command
  1047. `C-c C-f' (`texinfo-format-region').  This formats a region and
  1048. displays in a temporary buffer called `*Info Region*'; however, this
  1049. command does not turn on Info reading program--it just displays what
  1050. the region will look like.  The `texinfo-format-region' command is
  1051. described more extensively in the chapter on using Texinfo mode. 
  1052. *Note Info on a Region::.
  1053.  
  1054. In GNU Emacs, the way to create a working Info file is to visit the
  1055. file and invoke
  1056.  
  1057.      `M-x texinfo-format-buffer'
  1058.  
  1059. A new buffer is created and the Info file text is generated there. 
  1060. `C-x C-s' will save it under the name specified in the `@setfilename'
  1061. command.
  1062.  
  1063. If the Texinfo file has more than 30,000 bytes,
  1064. `texinfo-format-buffer' will automatically create a "tag table" for
  1065. it.  With a tag table, Info can jump to new nodes more quickly than
  1066. it can otherwise.  In addition, if the file has more than 100,000
  1067. bytes in it, `texinfo-format-buffer' will split the file into shorter
  1068. Indirect subfiles of about 50,000 bytes each.  Files are split so
  1069. that Info does not have to make a large buffer to hold the whole of a
  1070. large Info file; instead, Info allocates just enough memory for the
  1071. small, split off file that is needed at the time.  This way, Emacs
  1072. avoids wasting memory when you run Info.  (Before splitting was
  1073. implemented, Info files were always short and "include" files were
  1074. designed as a way to create a single, large printed manual out of the
  1075. smaller Info files. *Note Include Files::, for more information.)
  1076.  
  1077. When the file is split, Info itself works through a shortened version
  1078. of the original file that contains the tag table and references to
  1079. the files that were split off.  The split off files are called
  1080. "indirect" files.
  1081.  
  1082. The split off files have names that are created by appending `-1',
  1083. `-2', `-3' and so on to the file names specified by the
  1084. `@setfilename' command.  The shortened version of the original file
  1085. continues to have the name specified by `@setfilename'.
  1086.  
  1087. At one stage in writing this document, for example, the Info file was
  1088. saved as `test-texinfo' and that file looked like this:
  1089.  
  1090.      Info file: test-texinfo,    -*-Text-*-
  1091.      produced by texinfo-format-buffer
  1092.      from file: new-texinfo-manual.texinfo
  1093.      
  1094.      ^_
  1095.      Indirect:
  1096.      test-texinfo-1: 102
  1097.      test-texinfo-2: 50422
  1098.      test-texinfo-3: 101300
  1099.      ^_^L
  1100.      Tag table:
  1101.      (Indirect)
  1102.      Node: overview^?104
  1103.      Node: info file^?1271
  1104.      Node: printed manual^?4853
  1105.      Node: conventions^?6855
  1106.      ...
  1107.  
  1108.  (But `test-texinfo' had far more nodes than are shown here.)  Each of
  1109. the split off, indirect files, `test-texinfo-1', `test-texinfo-2',
  1110. and `test-texinfo-3', is listed in this file after the line that says
  1111. `Indirect:'.  The tag table is listed after the line that says `Tag
  1112. table:'.
  1113.  
  1114. You cannot run the `M-x Info-validate' node checking command on
  1115. indirect files.  For information on how to prevent files from being
  1116. split and how to validate the structure of the nodes, *note
  1117. Info-Validating a Large File::.
  1118.  
  1119. * Menu:
  1120.  
  1121. * Installing an Info File::    Putting the Info file in the info directory.
  1122.  
  1123.  
  1124. 
  1125. File: texinfo,  Node: Installing an Info File,  Prev: Creating an Info File,  Up: Creating an Info File
  1126.  
  1127. Installing an Info file
  1128. =======================
  1129.  
  1130. An Info file is usually installed in the GNU Emacs directory called
  1131. `info'.  For Info to work, this directory must contain all the Info
  1132. files, including the split off files.  In addition, the `info'
  1133. directory must have a file that serves as a top level directory for
  1134. the Info system.  This file is called `dir'.
  1135.  
  1136. For example, in the `info' directory, the file called `dir' has the
  1137. top level menu for all the Info files in the system.  This file has a
  1138. master menu that looks like this:
  1139.  
  1140.      * Menu:
  1141.      
  1142.      * Info:    (info).      Documentation browsing system.
  1143.      * Emacs:   (emacs).     The extensible self-documenting text editor.
  1144.      * Texinfo: (texinfo).   With one source file, make either a printed 
  1145.                              manual using TeX or an Info file using
  1146.                              Texinfo.
  1147.  
  1148.  To add a new Info file, just add it to this menu.  For example, if
  1149. you were adding documentation for GDB, you would make the following
  1150. entry:
  1151.  
  1152.      * GDB: (gdb).           The source-level C debugger.
  1153.  
  1154.  The first item is the menu item name; it is followed by a colon.  The
  1155. second item is the name of the Info file, in parentheses; it is
  1156. followed by a period.  The third part of the entry is the description
  1157. of the item.
  1158.  
  1159. The top node of the file, named `top', should have as its parent the
  1160. name of a node in another file, where there is a menu that leads to
  1161. this file.  Specify the file name in parentheses.  If the file is to
  1162. be installed directly in the Info directory file, use `(dir)' as the
  1163. parent of the top node; this is short for `(dir)top', the node `top'
  1164. in the file `dir', which is the main menu of Info.
  1165.  
  1166.  
  1167. 
  1168. File: texinfo,  Node: Catching Mistakes,  Next: Command Syntax,  Prev: Creating an Info File,  Up: Top
  1169.  
  1170. Catching Mistakes
  1171. *****************
  1172.  
  1173. Besides mistakes with the content of what ever you are describing,
  1174. there are two kinds of mistake you can make with Texinfo:  you can
  1175. make mistakes with @-commands, and you can make mistakes with the
  1176. structure of the nodes and chapters.
  1177.  
  1178. There are two tools for catching the first kind of mistake and two
  1179. for catching the second.
  1180.  
  1181. For finding problems with @-commands, your best action is to run `M-x
  1182. texinfo-format-region' on regions of your file as you write it.  In
  1183. Texinfo mode, the `texinfo-format-region' command is bound to `C-c
  1184. C-f'.  In addition, you can run TeX on the whole file.
  1185.  
  1186. For finding problems with the structure of nodes and chapters, you
  1187. can use `C-c C-s' (`texinfo-show-structure') (and the related `occur'
  1188. command) and you can use the `M-x Info-validate' command.
  1189.  
  1190. * Menu:
  1191.  
  1192. * Debugging with Info::            Catching errors with info formatting.
  1193. * Debugging with Tex::            Catching errors with TeX formatting.
  1194. * Using texinfo-show-structure::    Using `texinfo-show-structure'
  1195.                     to catch mistakes.
  1196. * Running Info-Validate::        Checking for unreferenced nodes.
  1197.  
  1198.  
  1199. 
  1200. File: texinfo,  Node: Debugging with Info,  Next: Debugging with Tex,  Up: Catching Mistakes
  1201.  
  1202. Catching Errors with Info Formatting
  1203. ====================================
  1204.  
  1205. After you have written part of a Texinfo file, you can use the `M-x
  1206. texinfo-format-region' command to see whether the region formats
  1207. properly.  In Texinfo mode, this command is bound to the keyboard
  1208. command `C-c C-f'.
  1209.  
  1210. If you have made a mistake with an @-command, `M-x
  1211. texinfo-format-region' will stop processing at or after the error and
  1212. give an error message.  To see where in the file the error occurred,
  1213. switch to the `*Info Region*' buffer; the cursor will be in a
  1214. position that is after the location of the error.  Also, the text
  1215. will not be formatted after the place the error occurred.
  1216.  
  1217. For example, if you accidently end a menu with the command `@end
  1218. menus' with an `s' on the end, instead of with `@end menu', you will
  1219. get an error message that says:
  1220.  
  1221.      @end menus is not handled by texinfo.
  1222.  
  1223.  The cursor will stop at the point in the file where the error occurs,
  1224. or not long after it.  It will look like this:
  1225.  
  1226.      @menu
  1227.      * Using texinfo-show-structure::    Using `texinfo-show-structure'
  1228.                                          to catch mistakes.
  1229.      * Running Info-Validate::           Checking for unreferenced nodes.
  1230.      @end menus
  1231.  
  1232. The `texinfo-format-region' command does not always recognize errors.
  1233. For example, no errors were reported when `texinfo-format-region' was
  1234. run on the whole itemized list of which the following is a part:
  1235.  
  1236.      name of the Texinfo file as an extension.  The @samp{??} are `wildcards'
  1237.      that cause the shell to substitute all the raw index files.  (@xref{sorting
  1238.      indices), for more information about sorting indices.) @refill
  1239.      @cindex Sorting indices
  1240.      @cindex Indices, sorting
  1241.      
  1242.      @item 
  1243.      @emph{Third}, rerun the @TeX{} command on the Texinfo file.  This
  1244.      regenerates a formatted DVI file with the index entries in the correct
  1245.      order.  This second run also makes all the cross references and table of
  1246.      contents correct as well.
  1247.  
  1248.  Instead, `texinfo-format-region' ran without reporting the error, but
  1249. it produced output with very long lines, containing some of the
  1250. original `@cindex' commands mixed in.  (It is not practical to
  1251. display these over long lines here.
  1252.  
  1253. However, when `texinfo-format-region' was run on part of the list
  1254. that is shown, it did give an error message, `Search failed: "[{,}"'.
  1255. (This error message is explained in the section on using the Emacs
  1256. Lisp Debugger, *note Using the Emacs Lisp Debugger::.)
  1257.  
  1258. Sometimes `texinfo-format-region' will stop long after the original
  1259. error;  this is because it does not discover the problem until then. 
  1260. In this case, you will have to backtrack.
  1261.  
  1262.  
  1263. 
  1264. File: texinfo,  Node: Using the Emacs Lisp Debugger,  Up: Debugging with Info
  1265.  
  1266. Using the Emacs Lisp Debugger
  1267. -----------------------------
  1268.  
  1269. If an error is especially elusive, you can turn on the Emacs Lisp
  1270. debugger and look at the backtrace; this tells you where in the
  1271. `texinfo-format-region' function the problem occurred.  You can turn
  1272. on the debugger with the command:
  1273.  
  1274.      M-x set-variable RET debug-on-error RET t
  1275.  
  1276. and turn it off with
  1277.  
  1278.      M-x set-variable RET debug-on-error RET nil
  1279.  
  1280. Often, when you are using the debugger, it is easier to follow what
  1281. is going on if you use the Emacs Lisp files that are not
  1282. byte-compiled.  The byte-compiled sources send octal numbers to the
  1283. debugger that may look mysterious.  To use the uncompiled source
  1284. files, load `texinfmt.el' and `texinfo.el' with the `M-x load-file'
  1285. command.
  1286.  
  1287. The debugger will not catch an error if `texinfo-format-region' does
  1288. not detect one.  In the example shown above, `texinfo-format-region'
  1289. did not find the error when the whole list was formatted, but only
  1290. when part of the list was formatted.  When `texinfo-format-region'
  1291. did not find an error, the debugger did not find one either.
  1292.  
  1293. However, when `texinfo-format-region' did report an error, it invoked
  1294. the debugger.  This is the backtrace it produced:
  1295.  
  1296.      Signalling: (search-failed "[},]")
  1297.        re-search-forward("[},]")
  1298.        (while ...)
  1299.        (let ...)
  1300.        texinfo-format-parse-args()
  1301.        (let ...)
  1302.        texinfo-format-xref()
  1303.        funcall(texinfo-format-xref)
  1304.        (if ...)
  1305.        (let ...)
  1306.        (if ...)
  1307.        (while ...)
  1308.        texinfo-format-scan()
  1309.        (save-excursion ...)
  1310.        (let ...)
  1311.        texinfo-format-region(103370 103631)
  1312.      * call-interactively(texinfo-format-region)
  1313.  
  1314. The backtrace is read from the bottom up.  `texinfo-format-region'
  1315. was called interactively; and it, in turn, called various functions,
  1316. including `texinfo-format-scan', `texinfo-format-xref' and
  1317. `texinfo-format-parse-args'.  Inside the function
  1318. `texinfo-format-parse-args', the function `re-search-forward' was
  1319. called; it was this function that could not find the missing right
  1320. hand brace.
  1321.  
  1322. *Note : (emacs)Lisp Debug, for more information.
  1323.  
  1324.  
  1325. 
  1326. File: texinfo,  Node: Debugging with Tex,  Next: Using texinfo-show-structure,  Prev: Debugging with Info,  Up: Catching Mistakes
  1327.  
  1328. Catching Errors with TeX Formatting
  1329. ===================================
  1330.  
  1331. You can also catch mistakes when you format a file with TeX.
  1332.  
  1333. Usually, you will want to do this after you have run
  1334. `texinfo-format-buffer' on the same file.  `texinfo-format-buffer' is
  1335. usually faster and sometimes gives error messages that make more
  1336. sense.  *Note Debugging with Info::, for more information.
  1337.  
  1338. For example, TeX was run on the same itemized list discussed in the
  1339. section on the use of  `texinfo-format-region' (*note Debugging with
  1340. Info::.); the fragment with the error looked like this:
  1341.  
  1342.      name of the texinfo file as an extension.  The @samp{??} are `wildcards'
  1343.      that cause the shell to substitute all the raw index files.  (@xref{sorting
  1344.      indices, for more information about sorting indices.) @refill
  1345.  
  1346. This produced the following output, after which TeX stopped:
  1347.  
  1348.      Runaway argument?
  1349.      {sorting indices, for more information about sorting indices.) @refill @ETC.
  1350.      ! Paragraph ended before \xref was complete.
  1351.      <to be read again> 
  1352.                         \par 
  1353.      l.27 
  1354.           
  1355.      ?
  1356.  
  1357. In this case, TeX produced an accurate and understandable error
  1358. message: `Paragraph ended before \xref was complete.' (Note, however,
  1359. that TeX translated the `@' into a `\'.)  Also, `\par' is an internal
  1360. TeX command of no relevance to Texinfo.)
  1361.  
  1362. Unfortunately, TeX is not always so helpful, and sometimes you have
  1363. to be truly a Sherlock Holmes to discover what went wrong.
  1364.  
  1365. In any case, if you run into a problem like this, you can do one of
  1366. two things.
  1367.  
  1368.   1. You can tell TeX to continue running and to ignore errors  as
  1369.      best it can by typing `r RET' at the  `?' prompt.
  1370.  
  1371.      This is often the best thing to do.  However, beware: the one
  1372.      error may produce a cascade of additional error messages as it
  1373.      consequences are felt through the rest of the file.
  1374.  
  1375.   2. You can tell TeX to stop this run by typing `x RET'  at the `?'
  1376.      prompt.
  1377.  
  1378. Sometimes TeX will format a file without producing error messages
  1379. even though there is a problem.  This usually occurs if a command is
  1380. not ended but TeX is able to continue processing anyhow.  For
  1381. example, if you fail to end an itemized list with the `@end itemize'
  1382. command, TeX will write a DVI file that you can print out.  The only
  1383. error message that TeX will give you is the somewhat mysterious
  1384. comment that
  1385.  
  1386.      (\end occurred inside a group at level 1)
  1387.  
  1388. However, if you print the DVI file, you will find that the text of
  1389. the file that follows the itemized list is entirely indented as if it
  1390. were part of the last item in the itemized list.  The error message
  1391. is the way TeX says that it expected to find an `@end' command
  1392. somewhere in the file; but that it could not locate where it was
  1393. needed.
  1394.  
  1395. Another source of notoriously hard to find errors is a missing `@end
  1396. group' command.  If you ever are stumped by incomprehensible errors,
  1397. look for a missing `@end group' command first.
  1398.  
  1399. If you do not have the header lines in the file, TeX may stop in the
  1400. beginning of its run and display output that looks like the following.
  1401. The `*' indicates that TeX is waiting for input.
  1402.  
  1403.      This is TeX, Version 2.0 for Berkeley UNIX (preloaded format=plain-cm 
  1404.      87.10.25) (#tz-bar-a02987.tex [1])
  1405.      *
  1406.  
  1407. In this case, simply type `\end RET' after the asterisk.  Then put
  1408. the header lines into the Texinfo file and run the TeX command again.
  1409.  
  1410.  
  1411.